<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Shard request cache settings | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="settings.html" title="Configuring Elasticsearch">
<link rel="prev" href="security-settings.html" title="Security settings in Elasticsearch">
<link rel="next" href="slm-settings.html" title="Snapshot lifecycle management settings in Elasticsearch">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="setup.html">Set up Elasticsearch</a></span>
»
<span class="breadcrumb-link"><a href="settings.html">Configuring Elasticsearch</a></span>
»
<span class="breadcrumb-node">Shard request cache settings</span>
</div>
<div class="navheader">
<span class="prev">
<a href="security-settings.html">« Security settings in Elasticsearch</a>
</span>
<span class="next">
<a href="slm-settings.html">Snapshot lifecycle management settings in Elasticsearch »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="shard-request-cache"></a>Shard request cache settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/modules/indices/request_cache.asciidoc">edit</a>
</h2>
</div></div></div>
<p>When a search request is run against an index or against many indices, each
involved shard executes the search locally and returns its local results to
the <em>coordinating node</em>, which combines these shard-level results into a
“global” result set.</p>
<p>The shard-level request cache module caches the local results on each shard.
This allows frequently used (and potentially heavy) search requests to return
results almost instantly. The requests cache is a very good fit for the logging
use case, where only the most recent index is being actively updated — results from older indices will be served directly from the cache.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>By default, the requests cache will only cache the results of search requests
where <code class="literal">size=0</code>, so it will not cache <code class="literal">hits</code>,
but it will cache <code class="literal">hits.total</code>,  <a class="xref" href="search-aggregations.html" title="Aggregations">aggregations</a>, and
<a class="xref" href="search-suggesters.html" title="Suggesters">suggestions</a>.</p>
<p>Most queries that use <code class="literal">now</code> (see <a class="xref" href="common-options.html#date-math" title="Date Math">Date Math</a>) cannot be cached.</p>
<p>Scripted queries that use the API calls which are non-deterministic, such as
<code class="literal">Math.random()</code> or <code class="literal">new Date()</code> are not cached.</p>
</div>
</div>
<h4>
<a id="_cache_invalidation"></a>Cache invalidation<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/modules/indices/request_cache.asciidoc">edit</a>
</h4>
<p>The cache is smart — it keeps the same <em>near real-time</em> promise as uncached
search.</p>
<p>Cached results are invalidated automatically whenever the shard refreshes, but
only if the data in the shard has actually changed.  In other words, you will
always get the same results from the cache as you would for an uncached search
request.</p>
<p>The longer the refresh interval, the longer that cached entries will remain
valid. If the cache is full, the least recently used cache keys will be
evicted.</p>
<p>The cache can be expired manually with the <a class="xref" href="indices-clearcache.html" title="Clear cache API"><code class="literal">clear-cache</code> API</a>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /kimchy,elasticsearch/_cache/clear?request=true</pre>
</div>
<div class="console_widget" data-snippet="snippets/28.console"></div>
<h4>
<a id="_enabling_and_disabling_caching"></a>Enabling and disabling caching<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/modules/indices/request_cache.asciidoc">edit</a>
</h4>
<p>The cache is enabled by default, but can be disabled when creating a new
index as follows:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /my_index
{
  "settings": {
    "index.requests.cache.enable": false
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/29.console"></div>
<p>It can also be enabled or disabled dynamically on an existing index with the
<a class="xref" href="indices-update-settings.html" title="Update index settings API"><code class="literal">update-settings</code></a> API:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /my_index/_settings
{ "index.requests.cache.enable": true }</pre>
</div>
<div class="console_widget" data-snippet="snippets/30.console"></div>
<h4>
<a id="_enabling_and_disabling_caching_per_request"></a>Enabling and disabling caching per request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/modules/indices/request_cache.asciidoc">edit</a>
</h4>
<p>The <code class="literal">request_cache</code> query-string parameter can be used to enable or disable
caching on a <span class="strong strong"><strong>per-request</strong></span> basis.  If set, it overrides the index-level setting:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /my_index/_search?request_cache=true
{
  "size": 0,
  "aggs": {
    "popular_colors": {
      "terms": {
        "field": "colors"
      }
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/31.console"></div>
<p>Requests where <code class="literal">size</code> is greater than 0 will not be cached even if the request cache is
enabled in the index settings. To cache these requests you will need to use the
query-string parameter detailed here.</p>
<h4>
<a id="_cache_key"></a>Cache key<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/modules/indices/request_cache.asciidoc">edit</a>
</h4>
<p>The whole JSON body is used as the cache key.  This means that if the JSON
changes — for instance if keys are output in a different order — then the
cache key will not be recognised.</p>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>Most JSON libraries support a <em>canonical</em> mode which ensures that JSON
keys are always emitted in the same order. This canonical mode can be used in
the application to ensure that a request is always serialized in the same way.</p>
</div>
</div>
<h4>
<a id="_cache_settings"></a>Cache settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/modules/indices/request_cache.asciidoc">edit</a>
</h4>
<p>The cache is managed at the node level, and has a default maximum size of <code class="literal">1%</code>
of the heap.  This can be changed in the <code class="literal">config/elasticsearch.yml</code> file with:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">indices.requests.cache.size: 2%</pre>
</div>
<p>Also, you can use the <code class="literal">indices.requests.cache.expire</code> setting to specify a TTL
for cached results, but there should be no reason to do so.  Remember that
stale results are automatically invalidated when the index is refreshed. This
setting is provided for completeness' sake only.</p>
<h4>
<a id="_monitoring_cache_usage"></a>Monitoring cache usage<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/modules/indices/request_cache.asciidoc">edit</a>
</h4>
<p>The size of the cache (in bytes) and the number of evictions can be viewed
by index, with the <a class="xref" href="indices-stats.html" title="Index stats API"><code class="literal">indices-stats</code></a> API:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_stats/request_cache?human</pre>
</div>
<div class="console_widget" data-snippet="snippets/32.console"></div>
<p>or by node with the <a class="xref" href="cluster-nodes-stats.html" title="Nodes stats API"><code class="literal">nodes-stats</code></a> API:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_nodes/stats/indices/request_cache?human</pre>
</div>
<div class="console_widget" data-snippet="snippets/33.console"></div>
</div>
<div class="navfooter">
<span class="prev">
<a href="security-settings.html">« Security settings in Elasticsearch</a>
</span>
<span class="next">
<a href="slm-settings.html">Snapshot lifecycle management settings in Elasticsearch »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
